eBay::API::XML::Session(3)

NAME
eBay::API::XML::Session - Cluster and submit several eBay XML API calls at once

INHERITANCE
eBay::API::XML::Session inherits from the eBay::API::XML::BaseXml class

DESCRIPTION
This module collects multiple requests to the eBay XML API and submits them sequentially or in parallel. Session.pm uses the CPAN module, LWP::Parallel, to manage the parallel submission of HTTP requests to the eBay XML API.

SYNOPSIS
  use eBay::API::XML::Call::GeteBayOfficialTime;
  use eBay::API::XML::Call::GetUser;
  use eBay::API::XML::DataType::Enum::DetailLevelCodeType;
  use eBay::API::XML::Call::GetSearchResults;
  use eBay::API::XML::DataType::PaginationType;
  use eBay::API::XML::Session;

  # Create a session (authorization info is pulled from ENV by the constructors)
  my $session = new eBay::API::XML::Session;

  # Get official time.
  my $pCall = eBay::API::XML::Call::GeteBayOfficialTime->new();
  $session->addRequest($pCall);

  # Get user details
  my $getUserCall = eBay::API::XML::Call::GetUser->new();
  $getUserCall->setDetailLevel( [eBay::API::XML::DataType::Enum::DetailLevelCodeType::ReturnAll] );
  $session->addRequest($getUserCall);

  # Get search results
  my $getListingsCall = new eBay::API::XML::Call::GetSearchResults;
  $getListingsCall->setQuery("new");
  my $pagination = new eBay::API::XML::DataType::PaginationType;
  $pagination->setEntriesPerPage(10);
  $getListingsCall->setPagination($pagination);
  $session->addRequest($getListingsCall);

  # session will submit the calls in parallel -- then wait til all come back
  $session->execute();

  # get results from various calls
  my $itemarray = $getListingsCall->getSearchResultItemArray()->getSearchResultItem();
  my $officialtime = $pCall->getEBayOfficialTime();
  my $pUser = $getUserCall->getUser();
  my $sEmail = $pUser->getEmail();
  my $sStatusCode = $pUser->getStatus();
  my $sSiteCode  = $pUser->getSite();

Subroutines:

  new()
Session constructor. This constructor delegates most of the work to the constructor for the abstract parent class, eBay::API::BaseApi. See perldoc eBay::API::BaseApi for more details.

Arguments:

•   sequential If this is true (non-zero), then the bundled calls will be executed sequentially. See method setSequentialExecution() for more details.

Returns:

•   success A reference to a blessed Session object.

•   error Undefined if an exception was encountered during construction of the session object. In that case, consult the log file for more details.

  addRequest()
Instance method to add an eBay::API::XML::Call to the request bundle.

Arguments:

•   Object reference of type eBay::API::XML::Session

•   Reference to an eBay::API::XML::Call to be issued to the eBay XML API.

•   Optional reference to a callback subroutine to be called when the http request returns. Note. This subroutine will be called whether the return is a success, a failure, or a timeout.

    Argument going to the callback subroutine is the call object it is associated with.

Returns: None

  clearSession()
Reset an eBay::API::XML::Session object so it may be re-used.

This involves the following:

•   Remove all bundled eBay::API::XML::Request objects.

•   Clear error information if present.

Arguments:

•   Object reference of type eBay::API::XML::Session

Returns:

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

•   failure undefined

  execute()
Instance method used for executing the actual XML API request bundle. This method really does most of the work. It will attempt to perform all necessary validations, as well as create and send the bundle of XML requests.

This method will block until all issued requests have responses, or until the timeout. After the responses come back from the API, they are populated back into the call objects registered with the session so they can be accessed from the client application.

execute() also returns the eBay::API::XML::Response objects in an array. This array may have responses for all, some, or none of the issued requests, depending on the success or failure of each request.

If the client application wants to use the request objects in the returned array, it should match up each response in the array with the corresponding request. This can best be done by using and tracking a unique message id for each request.

If an incomplete set of responses are returned, an appropriate error will be set and available to the getError() method.

Arguments:

•   Object reference of type eBay::API::XML::Session

Returns:

•   success Reference to array of api call objects submittted to the eBay API. The calls may, or may not have executed successfully; it is up to the user to check error status of the session and possibly individual calls.

•   failure undefined

  isSequentialExecution()
Returns current state of the session with regard to whether session calls should be executed in sequence as an ordered transaction rather than in parallel.

Arguments:

•   Object reference of type eBay::API::XML::Session.

Returns:

•   zero - true Session is set to issue calls in parallel.

•   non-zero - true Session will issue calls sequentially.

  setSequentialExecution()
Instance method to prepare the session to execute the API requests bundled in the session in the sequence in which they were added to the session. The only difference between this and the normal execution state is that the execute() method will execute each api call asynchronously rather than in parallel. If an error is encountered, none of the calls after the error was encountered will be sent to the eBay API. This behavior, in effect, offers a kind application-level transaction integrity, although there is no concept of 'rollback' in the sense of backing out the effects of calls executed prior to the error was encountered.

See the description of the execute() subroutine for more details.

Arguments:

•   Object reference of type eBay::API::XML::Session.

•   Boolean. True will set execution mode to sequential. False will set execution mode to parallel.

Returns:

•   success Value set for execution mode.

•   failure undefined