Tim Keefer > eBay-API > eBay::API::XML::Session

Download:
eBay-API-0.25.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Source  

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:

Returns:

addRequest()

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

Arguments:

Returns: None

clearSession()

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

This involves the following:

Arguments:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

syntax highlighting: