org.mbari.tethys.rest.client

Class ApiClient

java.lang.Object

org.mbari.tethys.rest.client.ApiClient

public class ApiClient
extends Object

High-level TethysDash API Client.

Status: Preliminary.

Note: The primary documentation is located at http://docs.mbari.org/tethysdash/apidocs/. For the most part the operation signatures in this class follow the corresponding descriptions in that documentation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ApiClient.Event
static class	ApiClient.GetCommandsResponse
static class	ApiClient.GetDeploymentsResponse
static class	ApiClient.GetEventsResponse
static class	ApiClient.GetInfoResponse
static class	ApiClient.GetMissionDefinitionSummaryResponse
static class	ApiClient.GetMissionsResponse
static class	ApiClient.GetMissionStartedEventsResponse
static class	ApiClient.MissionStartedEvent
static class	ApiClient.RemoveFutureSimEventsResponse
static class	ApiClient.ResponseException
static class	ApiClient.SendCommandsResponse
static class	ApiClient.SendNoteResponse
static class	ApiClient.UnauthenticatedException

Constructor Summary

Constructors

Constructor and Description
ApiClient(String restEndpoint) Creates an instance

Method Summary

Methods

Modifier and Type	Method and Description
String	authenticate(String email, String password) Call this method once prior to any request requiring authentication.
ApiClient.GetCommandsResponse	getCommands() Gets information about all possible commands.
ApiClient.GetDeploymentsResponse	getDeployments(String vehicle) Gets all deployments associated with a vehicle.
ApiClient.GetEventsResponse	getEvents(String vehicles, String eventTypes, String from, String to, int limit)
ApiClient.GetInfoResponse	getInfo()
ApiClient.GetMissionStartedEventsResponse	getLatestMissionStartedEvents(String vehicles, String to, int limit) Gets the latest "Started mission" events, up to the given maximum date, for the given vehicle(s).
ApiClient.GetMissionDefinitionSummaryResponse	getMissionDefinitionSummary(String tag, String filePath) Gets a summary of a mission definition.
ApiClient.GetMissionsResponse	getMissions(String tag, String subDir) Gets a list of mission files.
ApiClient.RemoveFutureSimEventsResponse	removeFutureSimEvents() Removes events timestamped in the future for the "sim" vehicle, which is often used in a mode that runs faster that real time.
ApiClient.SendCommandsResponse	sendCommands(String vehicle, String commandText, String commandNote, String schedDate, boolean runCommand) Sends commands to a vehicle.
ApiClient.SendNoteResponse	sendNote(String vehicle, String note) Sends a note.
void	setAuthenticationToken(String token) If already known, this method can be used to set the authentication token prior to any operation requiring it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ApiClient

public ApiClient(String restEndpoint)

Creates an instance

Parameters:

restEndpoint - TethysDash REST endpoint.

Method Detail

getInfo

public ApiClient.GetInfoResponse getInfo()
                                  throws IOException,
                                         URISyntaxException

Throws:

IOException

URISyntaxException

authenticate

public String authenticate(String email,
                  String password)
                    throws ApiClient.ResponseException,
                           IOException,
                           URISyntaxException

Call this method once prior to any request requiring authentication.

Parameters:

email - Email of user being authenticated

password - password

Returns:

authentication token

Throws:

ApiClient.ResponseException

IOException

URISyntaxException

setAuthenticationToken

public void setAuthenticationToken(String token)

If already known, this method can be used to set the authentication token prior to any operation requiring it.

Parameters:

token - the token

sendNote

public ApiClient.SendNoteResponse sendNote(String vehicle,
                                  String note)
                                    throws ApiClient.UnauthenticatedException,
                                           ApiClient.ResponseException,
                                           IOException,
                                           URISyntaxException

Sends a note.

Parameters:

vehicle - associated vehicle

note - the note

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException

getCommands

public ApiClient.GetCommandsResponse getCommands()
                                          throws ApiClient.UnauthenticatedException,
                                                 ApiClient.ResponseException,
                                                 IOException,
                                                 URISyntaxException

Gets information about all possible commands.

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException

getEvents

public ApiClient.GetEventsResponse getEvents(String vehicles,
                                    String eventTypes,
                                    String from,
                                    String to,
                                    int limit)
                                      throws ApiClient.UnauthenticatedException,
                                             ApiClient.ResponseException,
                                             IOException,
                                             URISyntaxException

Parameters:

vehicles - Comma-separated list of vehicle names. Can be null meaning all vehicles.

eventTypes - Comma-separated list of event types. Can be null meaning all event types.

from - Lower date limit in ISO-8601 format. Required.

to - Upper date limit in ISO-8601 format. null means current time.

limit - Maximum number of events to report. 0 or negative means 100.

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException

getLatestMissionStartedEvents

public ApiClient.GetMissionStartedEventsResponse getLatestMissionStartedEvents(String vehicles,
                                                                      String to,
                                                                      int limit)
                                                                        throws ApiClient.UnauthenticatedException,
                                                                               ApiClient.ResponseException,
                                                                               IOException,
                                                                               URISyntaxException

Gets the latest "Started mission" events, up to the given maximum date, for the given vehicle(s).

Parameters:

vehicles - Comma-separated list of vehicle names. Can be null meaning all vehicles.

to - Upper date limit in ISO-8601 format. null means current time.

limit - Maximum number of events to report. 0 or negative will mean the following actual limit: * 1 if a single vehicle has been indicated; * 100 otherwise.

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException

getMissions

public ApiClient.GetMissionsResponse getMissions(String tag,
                                        String subDir)
                                          throws ApiClient.UnauthenticatedException,
                                                 ApiClient.ResponseException,
                                                 IOException,
                                                 URISyntaxException

Gets a list of mission files.

Parameters:

tag - null (meaning "master"); "master"; or a particular tag in the "mission" git repository as configured for TethysDash.

subDir - Subdirectory to list (null is the same as "").

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException

getMissionDefinitionSummary

public ApiClient.GetMissionDefinitionSummaryResponse getMissionDefinitionSummary(String tag,
                                                                        String filePath)
                                                                          throws ApiClient.UnauthenticatedException,
                                                                                 ApiClient.ResponseException,
                                                                                 IOException,
                                                                                 URISyntaxException

Gets a summary of a mission definition.

Parameters:

tag - null (meaning "master"); "master"; or a particular tag in the "mission" git repository as configured for TethysDash.

filePath - Mission file to retrieve. For example, "Science/sci2.xml".

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException

removeFutureSimEvents

public ApiClient.RemoveFutureSimEventsResponse removeFutureSimEvents()
                                                              throws ApiClient.UnauthenticatedException,
                                                                     ApiClient.ResponseException,
                                                                     IOException,
                                                                     URISyntaxException

Removes events timestamped in the future for the "sim" vehicle, which is often used in a mode that runs faster that real time.

Returns:

Response

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException

sendCommands

public ApiClient.SendCommandsResponse sendCommands(String vehicle,
                                          String commandText,
                                          String commandNote,
                                          String schedDate,
                                          boolean runCommand)
                                            throws Exception

Sends commands to a vehicle.

Parameters:

vehicle -

commandText -

commandNote -

schedDate - For corresponding effect as in the TethysDash GUI: - null signifies "After mission" - "asap" signifies "ASAP" - other possible values TBD...

runCommand - true to generate a "run" event; otherwise, a "command" event is generated. A run of a mission is really just a command (or series of commands) being sent to the vehicle. It shows up differently in the UI to aid users in determining the difference between running a mission and just other commands that are sent to the vehicle.

Returns:

Response

Throws:

Exception

getDeployments

public ApiClient.GetDeploymentsResponse getDeployments(String vehicle)
                                                throws ApiClient.UnauthenticatedException,
                                                       ApiClient.ResponseException,
                                                       IOException,
                                                       URISyntaxException

Gets all deployments associated with a vehicle.

Parameters:

vehicle - Vehicle name. Can be null meaning all vehicles.

Throws:

ApiClient.UnauthenticatedException

ApiClient.ResponseException

IOException

URISyntaxException