edu.iastate.cs.boa

Class BoaClient

java.lang.Object

edu.iastate.cs.boa.BoaClient

All Implemented Interfaces:

AutoCloseable

public class BoaClient
extends Object
implements AutoCloseable

A client class for accessing Boa's API.

To use this class, first construct an object by either using the default constructor (to use the standard API domain/path) or providing the domain/path to the API. Then call login(java.lang.String username, java.lang.String password) with your Boa username and password to log into the remote API.

When finished with the object, close() must be called to log out of the remote API. The class is also AutoCloseable for use in a try-with-resources block.

Example usage:

 try (final BoaClient client = new BoaClient()) {
   client.login("user", "pass");

   // print all available input datasets
   for (final InputHandle d : client.getDatasets())
     System.out.println(d);

   // print info about the last job submitted
   System.out.println("Last job submitted: " + client.getLastJob());
 }
 

Author:

rdyer

Constructor Summary

Constructors

Constructor and Description
BoaClient() Create a new Boa API client, using the standard domain/path.
BoaClient(String domain, String path) Create a new Boa API client by providing the domain/path to the API.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Logs out of the Boa API.
InputHandle	getDataset(String name) Given the name of an input dataset, returns a handle (if one exists, otherwise null).
String[]	getDatasetNames() Returns an array of available input dataset names.
List<InputHandle>	getDatasets() Returns a list of available input datasets.
JobHandle	getJob(int id) Returns a specific job.
int	getJobCount() Returns the number of jobs for the user.
int	getJobCount(boolean pub) Returns the number of public (or all) jobs for the user.
List<JobHandle>	getJobList() Returns a list of the most recent jobs.
List<JobHandle>	getJobList(boolean pub) Returns a list of the most recent public (or all) jobs.
List<JobHandle>	getJobList(boolean pub, int offset, int length) Returns a list of the most recent public (or all) jobs, based on an offset and length.
List<JobHandle>	getJobList(int offset, int length) Returns a list of the most recent jobs, based on an offset and length.
JobHandle	getLastJob() Returns the most recent job.
void	login(String username, String password) Method to log into the remote API.
JobHandle	query(String query) Submits a new query to Boa to query the latest (testing) dataset and returns a handle to the new job.
JobHandle	query(String query, InputHandle dataset) Submits a new query to Boa to query the specified and returns a handle to the new job.
void	resetDatasetCache() Resets the internal dataset cache.

Methods inherited from class java.lang.Object

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

Constructor Detail

BoaClient

public BoaClient()

Create a new Boa API client, using the standard domain/path.

BoaClient

public BoaClient(String domain,
         String path)

Create a new Boa API client by providing the domain/path to the API.

Parameters:

domain - the domain hosting the API (can not contain '/')

path - the path to the API (must start with '/')

Method Detail

login

public void login(String username,
         String password)
           throws LoginException

Method to log into the remote API.

Parameters:

username - the Boa username to use to log in

password - the password for the user

Throws:

LoginException - if the login failed for any reason

close

public void close()
           throws BoaException

Logs out of the Boa API.

Specified by:

close in interface AutoCloseable

Throws:

BoaException - if the logout fails for any reason

resetDatasetCache

public void resetDatasetCache()

Resets the internal dataset cache.

getDatasets

public List<InputHandle> getDatasets()
                              throws BoaException,
                                     NotLoggedInException

Returns a list of available input datasets. Since datasets rarely change, the results may be up to 1 day old. The cache can be reset (see resetDatasetCache()).

Returns:

a Map where keys are dataset IDs and values are their names

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getDatasetNames

public String[] getDatasetNames()
                         throws BoaException,
                                NotLoggedInException

Returns an array of available input dataset names. Since datasets rarely change, the results may be up to 1 day old. The cache can be reset (see resetDatasetCache()).

Returns:

a Map where keys are dataset IDs and values are their names

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getDataset

public InputHandle getDataset(String name)
                       throws BoaException,
                              NotLoggedInException

Given the name of an input dataset, returns a handle (if one exists, otherwise null). Since datasets rarely change, the results may be up to 1 day old. The cache can be reset (see resetDatasetCache()).

Parameters:

name - the name of the input dataset to return a handle for

Returns:

an InputHandle for the specified dataset name

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getJob

public JobHandle getJob(int id)
                 throws BoaException,
                        NotLoggedInException

Returns a specific job.

Parameters:

id - the jobs id

Returns:

a JobHandle for the job

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getLastJob

public JobHandle getLastJob()
                     throws BoaException,
                            NotLoggedInException

Returns the most recent job.

Returns:

a JobHandle for the latest job, or null if no jobs exist

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getJobList

public List<JobHandle> getJobList()
                           throws BoaException,
                                  NotLoggedInException

Returns a list of the most recent jobs. The number of jobs is limited based on the user's web setting. This includes public and private jobs.

Returns:

a list of JobHandles for the most recent jobs

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getJobList

public List<JobHandle> getJobList(int offset,
                         int length)
                           throws BoaException,
                                  NotLoggedInException

Returns a list of the most recent jobs, based on an offset and length. This includes public and private jobs.

Parameters:

offset - the starting offset

length - the number of jobs (at most) to return

Returns:

a list of JobHandles for the jobs starting at the offset and containing at most length jobs

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getJobList

public List<JobHandle> getJobList(boolean pub)
                           throws BoaException,
                                  NotLoggedInException

Returns a list of the most recent public (or all) jobs. The number of jobs is limited based on the user's web setting.

Parameters:

pub - if true, only return public jobs otherwise return all jobs

Returns:

a list of JobHandles for the most recent jobs

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getJobList

public List<JobHandle> getJobList(boolean pub,
                         int offset,
                         int length)
                           throws BoaException,
                                  NotLoggedInException

Returns a list of the most recent public (or all) jobs, based on an offset and length.

Parameters:

pub - if true, only return public jobs otherwise return all jobs

offset - the starting offset

length - the number of jobs (at most) to return

Returns:

a list of JobHandles for the jobs starting at the offset and containing at most length jobs

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getJobCount

public int getJobCount()
                throws BoaException,
                       NotLoggedInException

Returns the number of jobs for the user. This includes public and private jobs.

Returns:

the number of jobs the user has created

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

getJobCount

public int getJobCount(boolean pub)
                throws BoaException,
                       NotLoggedInException

Returns the number of public (or all) jobs for the user.

Parameters:

pub - if true, return count of only public jobs otherwise return count of all jobs

Returns:

the number of jobs the user has created, possibly filtered to public only jobs

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

query

public JobHandle query(String query,
              InputHandle dataset)
                throws BoaException,
                       NotLoggedInException

Submits a new query to Boa to query the specified and returns a handle to the new job.

Parameters:

query - the query source code

dataset - the input dataset to query

Returns:

a JobHandle for the new job

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API

query

public JobHandle query(String query)
                throws BoaException,
                       NotLoggedInException

Submits a new query to Boa to query the latest (testing) dataset and returns a handle to the new job.

Parameters:

query - the query source code

Returns:

a JobHandle for the new job

Throws:

BoaException - if there was a problem reading from the server

NotLoggedInException - if not already logged in to the API