org.hackystat.telemetry.service.client
Class TelemetryClient

java.lang.Object
  extended by org.hackystat.telemetry.service.client.TelemetryClient

public class TelemetryClient
extends java.lang.Object

Provides a client to support access to the DailyProjectData service.

Author:
Philip Johnson

Field Summary
static java.lang.String TELEMETRYCLIENT_TIMEOUT_KEY
          The System property key used to retrieve the default timeout value in milliseconds.
 
Constructor Summary
TelemetryClient(java.lang.String host, java.lang.String email, java.lang.String password)
          Initializes a new TelemetryClient, given the host, userEmail, and password.
 
Method Summary
 TelemetryClient authenticate()
          Authenticates this user and password with this Telemetry service, throwing a TelemetryClientException if the user and password associated with this instance are not valid credentials.
 void clearServerCache()
          Clears the DailyProjectData cache associated with this user in the Telemetry service associated with this TelemetryClient.
 void clearServerCache(java.lang.String owner, java.lang.String project)
          Clears the DailyProjectData cache entries for this user that are associated with the passed project and its owner in the Telemetry service associated with this TelemetryClient.
 TelemetryChartData getChart(java.lang.String name, java.lang.String user, java.lang.String project, java.lang.String granularity, javax.xml.datatype.XMLGregorianCalendar start, javax.xml.datatype.XMLGregorianCalendar end)
          Returns a TelemetryChart instance from this server, or throws a TelemetryClientException if problems occur.
 TelemetryChartData getChart(java.lang.String name, java.lang.String user, java.lang.String project, java.lang.String granularity, javax.xml.datatype.XMLGregorianCalendar start, javax.xml.datatype.XMLGregorianCalendar end, java.lang.String params)
          Returns a TelemetryChart instance from this server, or throws a TelemetryClientException if problems occur.
 TelemetryChartDefinition getChartDefinition(java.lang.String chartName)
          Returns a TelemetryChartDefinition instance from this server, or throws a TelemetryClientException if problems occur.
 TelemetryChartIndex getChartIndex()
          Returns a TelemetryChartIndex instance from this server, or throws a TelemetryClientException if problems occur.
 java.lang.String getHostName()
          Returns the host associated with this Telemetry client.
static boolean isHost(java.lang.String host)
          Returns true if the passed host is a Telemetry host.
 void setTimeout(int milliseconds)
          Sets the timeout value for this client.
static java.lang.String toString(TelemetryChartData chart)
          Returns the passed telemetry chart data in a human-readable string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TELEMETRYCLIENT_TIMEOUT_KEY

public static final java.lang.String TELEMETRYCLIENT_TIMEOUT_KEY
The System property key used to retrieve the default timeout value in milliseconds.

See Also:
Constant Field Values
Constructor Detail

TelemetryClient

public TelemetryClient(java.lang.String host,
                       java.lang.String email,
                       java.lang.String password)
Initializes a new TelemetryClient, given the host, userEmail, and password. Note that the userEmail and password refer to the underlying SensorBase client associated with this Telemetry service. This service does not keep its own independent set of userEmails and passwords. Authentication is not actually performed in this constructor. Use the authenticate() method to explicitly check the authentication credentials.

Parameters:
host - The host, such as 'http://localhost:9878/telemetry'.
email - The user's email used for authentication.
password - The password used for authentication.
Method Detail

setTimeout

public final void setTimeout(int milliseconds)
Sets the timeout value for this client.

Parameters:
milliseconds - The number of milliseconds to wait before timing out.

authenticate

public TelemetryClient authenticate()
                             throws TelemetryClientException
Authenticates this user and password with this Telemetry service, throwing a TelemetryClientException if the user and password associated with this instance are not valid credentials. Note that authentication is performed by checking these credentials with the underlying SensorBase; this service does not keep its own independent set of usernames and passwords.

Returns:
This TelemetryClient instance.
Throws:
TelemetryClientException - If authentication is not successful.

getChart

public TelemetryChartData getChart(java.lang.String name,
                                   java.lang.String user,
                                   java.lang.String project,
                                   java.lang.String granularity,
                                   javax.xml.datatype.XMLGregorianCalendar start,
                                   javax.xml.datatype.XMLGregorianCalendar end)
                            throws TelemetryClientException
Returns a TelemetryChart instance from this server, or throws a TelemetryClientException if problems occur.

Parameters:
name - The chart name.
user - The user email.
project - The project.
granularity - Either Day, Week, or Month.
start - The start day.
end - The end day.
Returns:
The TelemetryChart instance.
Throws:
TelemetryClientException - If the credentials associated with this instance are not valid, or if the underlying SensorBase service cannot be reached, or if one or more of the supplied user, password, or timestamp is not valid.

getChart

public TelemetryChartData getChart(java.lang.String name,
                                   java.lang.String user,
                                   java.lang.String project,
                                   java.lang.String granularity,
                                   javax.xml.datatype.XMLGregorianCalendar start,
                                   javax.xml.datatype.XMLGregorianCalendar end,
                                   java.lang.String params)
                            throws TelemetryClientException
Returns a TelemetryChart instance from this server, or throws a TelemetryClientException if problems occur.

Parameters:
name - The chart name.
user - The user email.
project - The project.
granularity - Either Day, Week, or Month.
start - The start day.
end - The end day.
params - The parameter string, or null if no params are present.
Returns:
The TelemetryChart instance.
Throws:
TelemetryClientException - If the credentials associated with this instance are not valid, or if the underlying SensorBase service cannot be reached, or if one or more of the supplied user, password, or timestamp is not valid.

clearServerCache

public void clearServerCache()
                      throws TelemetryClientException
Clears the DailyProjectData cache associated with this user in the Telemetry service associated with this TelemetryClient.

Throws:
TelemetryClientException - If problems occur.

clearServerCache

public void clearServerCache(java.lang.String owner,
                             java.lang.String project)
                      throws TelemetryClientException
Clears the DailyProjectData cache entries for this user that are associated with the passed project and its owner in the Telemetry service associated with this TelemetryClient.

Parameters:
project - The project to be cleared.
owner - The owner of the project.
Throws:
TelemetryClientException - If problems occur.

getChartIndex

public TelemetryChartIndex getChartIndex()
                                  throws TelemetryClientException
Returns a TelemetryChartIndex instance from this server, or throws a TelemetryClientException if problems occur.

Returns:
The TelemetryChartIndex instance.
Throws:
TelemetryClientException - If the credentials associated with this instance are not valid, or if the underlying SensorBase service cannot be reached, or if one or more of the supplied user, password, or timestamp is not valid.

getChartDefinition

public TelemetryChartDefinition getChartDefinition(java.lang.String chartName)
                                            throws TelemetryClientException
Returns a TelemetryChartDefinition instance from this server, or throws a TelemetryClientException if problems occur.

Parameters:
chartName - The name of the chart whose definition is to be retrieved.
Returns:
The TelemetryChartDefinition instance.
Throws:
TelemetryClientException - If the credentials associated with this instance are not valid, or if the underlying SensorBase service cannot be reached, or if one or more of the supplied user, password, or timestamp is not valid.

isHost

public static boolean isHost(java.lang.String host)
Returns true if the passed host is a Telemetry host.

Parameters:
host - The URL of a Telemetry host, "http://localhost:9875/telemetry".
Returns:
True if this URL responds as a Telemetry host.

getHostName

public java.lang.String getHostName()
Returns the host associated with this Telemetry client.

Returns:
The host.

toString

public static java.lang.String toString(TelemetryChartData chart)
Returns the passed telemetry chart data in a human-readable string. For debugging purposes, this method is expensive.

Parameters:
chart - The chart data.
Returns:
The chart data, as a string.