edu.sdsc.inca
Class DepotClient

java.lang.Object
  edu.sdsc.inca.Component
      edu.sdsc.inca.Client
          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	deleteKbArticle(java.lang.String articleId) Asks the Depot to delete a knowledge base article from the database
void	insertKbArticle(java.lang.String articleXml) Asks the Depot to insert a knowledge base article in the database
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.
java.lang.String[]	queryDepotPeers() Asks the Depot for a list of its peer Depots
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(java.lang.String nickname, java.lang.String resource, java.util.Date collected) Asks the Depot for the ReportDetailsDocument for a specified instance.
java.lang.String	queryInstanceById(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, commandRevoke, commandRevokeAll, connect, dialog, getDn, getTempPath, isConnected, read, setServer, setTempPath, telnetDialog, write

Methods inherited from class edu.sdsc.inca.Component

addTrustedCert, configComponent, createSocket, getAuthenticate, getCertificate, getCertificatePath, getConfiguration, 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(java.lang.String nickname,
                                      java.lang.String resource,
                                      java.util.Date collected)
                               throws java.io.IOException,
                                      ProtocolException,
                                      org.apache.xmlbeans.XmlException

Asks the Depot for the ReportDetailsDocument for a specified instance.

Parameters:

nickname -

resource -

collected -

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

queryInstanceById

public java.lang.String queryInstanceById(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

insertKbArticle

public void insertKbArticle(java.lang.String articleXml)
                     throws java.io.IOException,
                            ProtocolException

Asks the Depot to insert a knowledge base article in the database

Parameters:

articleXml -

Throws:

java.io.IOException

ProtocolException

deleteKbArticle

public void deleteKbArticle(java.lang.String articleId)
                     throws java.io.IOException,
                            ProtocolException

Asks the Depot to delete a knowledge base article from the database

Parameters:

articleId -

Throws:

java.io.IOException

ProtocolException

queryDepotPeers

public java.lang.String[] queryDepotPeers()
                                   throws java.io.IOException,
                                          ProtocolException

Asks the Depot for a list of its peer Depots

Returns:

peer depot URIs, null if none

Throws:

java.io.IOException

ProtocolException

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.