edu.sdsc.inca
Class DepotClient

java.lang.Object
  extended by edu.sdsc.inca.Component
      extended by edu.sdsc.inca.Client
          extended by edu.sdsc.inca.DepotClient

public class DepotClient
extends Client

This class allows access to the services provided by an Inca Depot. Along with defining an API that understands the Depot protocol, it defines a main method that allows access to an Depot via a telnet-style interface.


Field Summary
static java.lang.String CRLF
           
static java.lang.String DEPOT_CLIENT_OPTS
           
protected static org.apache.log4j.Logger logger
           
static long MILLIS_IN_A_DAY
          Asks the Depot for XML that summarizes the success/failure history over a given period to today for each series selected by an HQL WHERE clause expression.
 
Fields inherited from class edu.sdsc.inca.Client
CLIENT_OPTS, reader, socket, writer
 
Fields inherited from class edu.sdsc.inca.Component
authenticate, cert, certPath, COMPONENT_OPTS, hostname, key, keyPath, logFile, password, port, trusted, trustedPath
 
Constructor Summary
DepotClient()
           
 
Method Summary
 void insertReport(java.lang.String resource, java.lang.String reportXml, java.lang.String sysusage, java.lang.String stderr, java.lang.String context)
          Asks the Depot to insert a new report into the database.
static void main(java.lang.String[] args)
          A simple main method for exercising the DepotClient.
 java.lang.String queryDatabase()
          Asks the Depot for information about the classes in the database.
protected  java.lang.String[] queryDialog(java.lang.String command, java.lang.String data)
          An internal method that handles the functionality common to several query methods.
protected  java.lang.String[] queryDialogWithNoSoTimeout(java.lang.String command, java.lang.String data)
          An internal method that handles the functionality common to several query methods.
 java.lang.String[] queryGuids()
          Asks the Depot for all the suite guids in its database.
 java.lang.String[] queryHql(java.lang.String select)
          Asks the Depot to run an HQL query; returns the result.
 java.lang.String queryInstance(long instanceId, long configId)
          Asks the Depot for the ReportDetailsDocument for a specified instance.
 java.lang.String[] queryLatest(java.lang.String expr)
          Asks the Depot for XML for the latest instance of each series selected by an HQL WHERE clause expression.
 java.lang.String[] queryPeriod(java.util.Date begin, java.util.Date end, java.lang.String expr)
          Asks the Depot for XML for instances collected over a given period of time for each series selected by an HQL WHERE clause expression.
 java.lang.String[] queryPeriod(int numDays, java.lang.String expr)
          Asks the Depot for XML for instances collected over a given period of time for each series selected by an HQL WHERE clause expression.
 java.lang.String[] queryStatusHistory(java.lang.String period, java.util.Date begin, java.util.Date end, java.lang.String expr)
          Asks the Depot for XML that summarizes the success/failure history over a given period for each series selected by an HQL WHERE clause expression.
 java.lang.String[] queryStatusHistory(java.lang.String period, int numDays, java.lang.String expr)
           
 void resendReport(java.lang.String resource, java.lang.String reportXml, java.lang.String sysusage, java.lang.String stderr, java.lang.String context)
          Asks the Depot to insert a report that may predate existing reports into the database.
 void setConfiguration(java.util.Properties config)
          A convenience function for setting multiple configuration properties at once.
 java.lang.String updateSuite(java.lang.String suiteXml)
          Asks the Depot to add XML for a suite to its database, replacing any existing XML for the same suite.
 
Methods inherited from class edu.sdsc.inca.Client
close, commandGetLog, commandLogConfig, commandPermit, commandPing, connect, dialog, getDn, isConnected, read, setServer, telnetDialog, write
 
Methods inherited from class edu.sdsc.inca.Component
addTrustedCert, configComponent, createSocket, getAuthenticate, getCertificate, getCertificatePath, getDn, getHostname, getKey, getKeyPath, getLogFile, getPassword, getPort, getTrustedCertificates, getTrustedPath, getUri, openResourceStream, readCredentials, readVersion, setAuthenticate, setCertificatePath, setHostname, setKeyPath, setLogFile, setPassword, setPort, setTrustedPath
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CRLF

public static final java.lang.String CRLF
See Also:
Constant Field Values

DEPOT_CLIENT_OPTS

public static final java.lang.String DEPOT_CLIENT_OPTS

logger

protected static final org.apache.log4j.Logger logger

MILLIS_IN_A_DAY

public static long MILLIS_IN_A_DAY
Asks the Depot for XML that summarizes the success/failure history over a given period to today for each series selected by an HQL WHERE clause expression.

Constructor Detail

DepotClient

public DepotClient()
Method Detail

setConfiguration

public void setConfiguration(java.util.Properties config)
                      throws ConfigurationException
A convenience function for setting multiple configuration properties at once. In addition to the keys recognized by the superclass, recognizes: "depot", the specification of the Depot.

Overrides:
setConfiguration in class Client
Parameters:
config - contains client configuration values
Throws:
ConfigurationException - on a faulty configuration property value

insertReport

public void insertReport(java.lang.String resource,
                         java.lang.String reportXml,
                         java.lang.String sysusage,
                         java.lang.String stderr,
                         java.lang.String context)
                  throws java.io.IOException,
                         ProtocolException
Asks the Depot to insert a new report into the database.

Parameters:
resource - the name of the resource that generated the report
reportXml - the XML for the report itself (see report schema)
sysusage - system usage information
stderr - optional stderr output from the reporter
context - execution context for the reporter
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryDatabase

public java.lang.String queryDatabase()
                               throws java.io.IOException,
                                      ProtocolException
Asks the Depot for information about the classes in the database. Returns XML that specifies the name of each class and the names of its fields.

Returns:
XML that represents the DB structure
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryInstance

public java.lang.String queryInstance(long instanceId,
                                      long configId)
                               throws java.io.IOException,
                                      ProtocolException,
                                      org.apache.xmlbeans.XmlException
Asks the Depot for the ReportDetailsDocument for a specified instance.

Parameters:
instanceId - the id of the instance to retrieve
configId - the id of the related series config to retrieve
Returns:
the ReportDetailsDocument for the instance, null if none
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message
org.apache.xmlbeans.XmlException - if the Depot response cannot be parsed

queryGuids

public java.lang.String[] queryGuids()
                              throws java.io.IOException,
                                     ProtocolException
Asks the Depot for all the suite guids in its database.

Returns:
an array of guids
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryHql

public java.lang.String[] queryHql(java.lang.String select)
                            throws java.io.IOException,
                                   ProtocolException
Asks the Depot to run an HQL query; returns the result.

Parameters:
select - the HQL select query
Returns:
an array of strings, the result of the query
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryLatest

public java.lang.String[] queryLatest(java.lang.String expr)
                               throws java.io.IOException,
                                      ProtocolException
Asks the Depot for XML for the latest instance of each series selected by an HQL WHERE clause expression.

Parameters:
expr - an HQL WHERE clause expression specifying the desired series
Returns:
an array of XML strings representing each instance
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryPeriod

public java.lang.String[] queryPeriod(int numDays,
                                      java.lang.String expr)
                               throws java.io.IOException,
                                      ProtocolException
Asks the Depot for XML for instances collected over a given period of time for each series selected by an HQL WHERE clause expression.

Parameters:
numDays - the number of days of history to retrieve from today
expr - an HQL WHERE clause expression specifying the desired series
Returns:
an array of GraphInstance XML strings, one per instance
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryPeriod

public java.lang.String[] queryPeriod(java.util.Date begin,
                                      java.util.Date end,
                                      java.lang.String expr)
                               throws java.io.IOException,
                                      ProtocolException
Asks the Depot for XML for instances collected over a given period of time for each series selected by an HQL WHERE clause expression.

Parameters:
begin - series instances collected before this time are ignored
end - series instances collected after this time are ignored
expr - an HQL WHERE clause expression specifying the desired series
Returns:
an array of GraphInstance XML strings, one per instance
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryStatusHistory

public java.lang.String[] queryStatusHistory(java.lang.String period,
                                             int numDays,
                                             java.lang.String expr)
                                      throws java.io.IOException,
                                             ProtocolException
Throws:
java.io.IOException
ProtocolException

queryStatusHistory

public java.lang.String[] queryStatusHistory(java.lang.String period,
                                             java.util.Date begin,
                                             java.util.Date end,
                                             java.lang.String expr)
                                      throws java.io.IOException,
                                             ProtocolException
Asks the Depot for XML that summarizes the success/failure history over a given period for each series selected by an HQL WHERE clause expression.

Parameters:
period - the summarizing period; may be one of the literals "DAY", "WEEK", "MONTH", or "QUARTER" or a number of minutes
begin - series instances collected before this time are ignored
end - series instances collected after this time are ignored
expr - an HQL WHERE clause expression specifying the desired series
Returns:
an array of XML strings summarizing each series
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

resendReport

public void resendReport(java.lang.String resource,
                         java.lang.String reportXml,
                         java.lang.String sysusage,
                         java.lang.String stderr,
                         java.lang.String context)
                  throws java.io.IOException,
                         ProtocolException
Asks the Depot to insert a report that may predate existing reports into the database.

Parameters:
resource - the name of the resource that generated the report
reportXml - the XML for the report itself (see report schema)
sysusage - system usage information
stderr - optional stderr output from the reporter
context - execution context for the reporter
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

updateSuite

public java.lang.String updateSuite(java.lang.String suiteXml)
                             throws java.io.IOException,
                                    ProtocolException
Asks the Depot to add XML for a suite to its database, replacing any existing XML for the same suite.

Parameters:
suiteXml - XML representing the suite to be saved
Returns:
the reply message data
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryDialog

protected java.lang.String[] queryDialog(java.lang.String command,
                                         java.lang.String data)
                                  throws java.io.IOException,
                                         ProtocolException
An internal method that handles the functionality common to several query methods.

Parameters:
command - the command to send the Depot
data - the data to accompany the command
Returns:
an array of query response strings sent by the Depot
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

queryDialogWithNoSoTimeout

protected java.lang.String[] queryDialogWithNoSoTimeout(java.lang.String command,
                                                        java.lang.String data)
                                                 throws java.io.IOException,
                                                        ProtocolException
An internal method that handles the functionality common to several query methods. Similar to queryDialog but wil ignore socket timeouts up to MAX.

Parameters:
command - the command to send the Depot
data - the data to accompany the command
Returns:
an array of query response strings sent by the Depot
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

main

public static void main(java.lang.String[] args)
A simple main method for exercising the DepotClient.
 usage: java inca.DepotClient
-a|--auth boolean Authenticated (secure) connection? -c|--cert path Path to the authentication certificate -D|--depot str Depot specification; host:port -h|--help null Print help/usage -i|--init path Path to properties file -k|--key path Path to the authentication key -P|--password str Specify how to obtain encryption password -t|--trusted path Path to authentication trusted certificate dir -V|--version null Display program version

Each of these properties, other than --init, can also be specified in the initialization file or in system properties defined via the -D switch. In each of these cases, the configuration name must be prefixed with "inca.depot.", e.g., use "inca.depot.cert" to specify the cert value. Command line arguments override any properties specified in this fashion. main allows the user to communicate with the Depot via a telnet-style interface. Supported values for the --password argument are: "no" or "false" (no encryption); "yes", "true", or "stdin:prompt" (read password from stdin after optionally prompting); "pass:text" (specify the password directly--should only be used for testing and, possibly, in the init file).

Parameters:
args - command line arguments, as above.