<<

NAME

Inca::DepotClient - A perl module for defining clients of Inca depots.

SYNOPSIS

  use Inca::DepotClient;
  my $client = new Inca::DepotClient(
    host => 'localhost',
    port => 6362,
    auth => 1,
    cert => 'etc/mycert.pem',
    init => 'etc/inca.properties',
    key => 'etc/mykey.pem',
    prefix => 'inca.depot.',
    trusted => 'etc/mycert.pem',
    password => '1ncaD1nkaD00'
  );

DESCRIPTION

This module creates clients for Inca depots. It handles both unauthenticated and (where available) authenticated communication between client and server and implements methods that are supported by the inca depot.

CLASS METHODS

new

Class constructor which returns a new Inca::DepotClient object. The constructor may be called with any of the following named parameters.

auth

A boolean value indicating whether or not the connection to the depot should use certificate-based authentication. The default is false.

cert

The path to the certificate file. Required for authenticated connections.

host

The IP or DNS name of the depot to contact. Required.

init

Optional path to an Inca properties file specifying values for other parameters.

key

The path to the private key file. Required for authenticated connections.

password

The password for decripting the private key file. Required for authenticated connections.

port

The server port to contact. Required.

prefix

Optional prefix for properties in the init file. The constructor ignores properties that lack this prefix and strips the prefix from those that have it. Default 'inca.depot.'.

trusted

The path to the trusted ca certificate file. Required for authenticated connections.

insertReport($resource, $context, $reportDoc, $sysusage, $stderr)

Asks the depot to insert a new report into the database. $resource is the name of the resource that generated the report; $context is the execution context for the reporter; $reportDoc the XML for the report itself (see Inca Report schema); $sysusage a string indicating cpu, wall clock, and memory usage, and $stderr optional stderr output from the reporter. Returns any successful reply from the depot.

queryDb( )

Asks the depot to return XML that represents the structure of its database. Returns any succesful reply from the depot.

queryGuids( )

Asks the depot to return a newline-separated list of known suite guids. Returns any succesful reply from the depot.

queryHql($hql)

Asks the depot use the HQL select statement $hql to extract and return information from the DB. On success, returns a reference to an array that contains the objects selected by the select statement.

queryInstance($instanceId, $configId)

Asks the depot to report details about one particular invocation of a reporter. $instanceId is the DB id of the instance for the invocation; $configId the related series configuration DB id. On success, returns a reference to a single-element array that contains a ReportDetails document (see ReportDetails schema) describing the instance.

queryLatest($expr)

Asks the depot to retrieve information about all the series selected by $expr, which is an HQL WHERE clause expression. On success, returns a reference to an array that contains a set of ReportSummary documents (see ReportSummary schema) related to the series configurations of the suite.

queryPeriod($begin, $end, $expr)

Asks the depot to retrieve information on instances collected over a given period for all the series selected by $expr, which is an HQL WHERE clause expression. Both $begin and $end are a number of seconds since the epoch; only series instances collected on or after $begin and on or before $end are considered. On success, returns a reference to an array that contains a set of GraphInstance documents (see GraphSeries schema).

queryStatus($period, $begin, $end, $expr)

Asks the depot to retrieve information that summarizes the success/failure history over a given period for all the series selected by $expr, which is an HQL WHERE clause expression. $period is the summarizing period; it may be one of "DAY", "WEEK", "MONTH", "QUARTER" or a number of minutes. Both $begin and $end are a number of seconds since the epoch; only series instances collected on or after $begin and before $end are considered. On success, returns a reference to an array that contains a set of SeriesHistory documents (see SeriesHistory schema) related to the series configurations of the suite.

resendReport($resource, $context, $reportDoc, $sysusage, $stderr)

Asks the depot to insert a report that may predate existing reports into the database. $resource is the name of the resource that generated the report; $context is the execution context for the reporter; $reportDoc the XML for the report itself (see Inca Report schema); $sysusage a string indicating cpu, wall clock, and memory usage, and $stderr optional stderr output from the reporter. Returns any successful reply from the depot.

updateSuite($suiteDoc)

Asks the depot to update its information about a suite configuration based on the contents of the Suite document $suiteDoc (see Suite schema). Returns any successful reply from the depot.

readQueryResults( )

An internal method that reads a list of QUERYRESULT message from the depot and returns their data in an array reference.

<<