com.mobilyzer.api

Class API

java.lang.Object

com.mobilyzer.api.API

public final class API
extends java.lang.Object

Author:

jackjia,Hongyi Yao (hyyao@umich.edu) The user API for Mobiperf library. Use singleton design pattern to ensure there only exist one instance of API User: create and add task => Scheduler: run task, send finish intent => User: register BroadcastReceiver for userResultAction and serverResultAction

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	API.TaskType

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	authAccountAction
java.lang.String	batteryThresholdAction
java.lang.String	checkinIntervalAction
java.lang.String	dataUsageAction
static int	INVALID_PRIORITY
static java.lang.String	SERVER_RESULT_ACTION
java.lang.String	taskStatusAction
static int	USER_PRIORITY
java.lang.String	userResultAction Action name of different type of result for broadcast receiver.

Method Summary

Methods

Modifier and Type	Method and Description
void	cancelTask(java.lang.String taskId) Cancel the task submitted to the scheduler
java.lang.Object	clone()
com.mobilyzer.MeasurementTask	composeTasks(API.TaskType manner, java.util.Date startTime, java.util.Date endTime, double intervalSec, long count, long priority, int contextIntervalSec, java.util.Map<java.lang.String,java.lang.String> params, java.util.ArrayList<com.mobilyzer.MeasurementTask> taskList) Create a parallel or sequential task based on the manner.
com.mobilyzer.MeasurementTask	createTask(API.TaskType taskType, java.util.Date startTime, java.util.Date endTime, double intervalSec, long count, long priority, int contextIntervalSec, java.util.Map<java.lang.String,java.lang.String> params) Create a new MeasurementTask based on those parameters.
static API	getAPI(Context parent, java.lang.String clientKey) Actual method to get the singleton API object
void	getAuthenticateAccount() Get current authenticate account used by scheduler
void	getBatteryThreshold() Get current battery threshold of the scheduler.
void	getCheckinInterval() Get current checkin interval of the scheduler.
void	getDataUsage() Get current data usage of the scheduler.
static java.util.Set<java.lang.String>	getMeasurementNames() Gets the currently available measurement descriptions
void	getTaskStatus(java.lang.String taskId) Get current status of that task.
static java.lang.String	getTypeForMeasurementName(java.lang.String name) Get the type of a measurement based on its name.
void	setAuthenticateAccount(java.lang.String account) Set authenticate account for uploading results.
void	setBatteryThreshold(int threshold) Set battery threshold of the scheduler.
void	setCheckinInterval(long interval) Set checkin interval of the scheduler.
void	setDataUsage(com.mobilyzer.MeasurementScheduler.DataUsageProfile profile) Set data usage profile of the scheduler.
void	startAndBindService() Bind to scheduler, automatically called when the API is initialized
void	submitTask(com.mobilyzer.MeasurementTask task) Submit task to the scheduler.
void	unbind() Unbind from scheduler, called in activity's onDestroy callback function

Methods inherited from class java.lang.Object

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

Field Detail

userResultAction

public java.lang.String userResultAction

Action name of different type of result for broadcast receiver. userResultAction is not a constant value. We append the clientKey to UpdateIntent.USER_RESULT_ACTION so that only the user who submit the task can get the result

SERVER_RESULT_ACTION

public static final java.lang.String SERVER_RESULT_ACTION

batteryThresholdAction

public java.lang.String batteryThresholdAction

checkinIntervalAction

public java.lang.String checkinIntervalAction

taskStatusAction

public java.lang.String taskStatusAction

dataUsageAction

public java.lang.String dataUsageAction

authAccountAction

public java.lang.String authAccountAction

USER_PRIORITY

public static final int USER_PRIORITY

See Also:

Constant Field Values

INVALID_PRIORITY

public static final int INVALID_PRIORITY

See Also:

Constant Field Values

Method Detail

getAPI

public static API getAPI(Context parent,
         java.lang.String clientKey)

Actual method to get the singleton API object

Parameters:

parent - Context which the object lies in

clientKey - User-defined unique key for this application

Returns:

Singleton API object

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

Throws:

java.lang.CloneNotSupportedException

startAndBindService

public void startAndBindService()

Bind to scheduler, automatically called when the API is initialized

unbind

public void unbind()

Unbind from scheduler, called in activity's onDestroy callback function

createTask

public com.mobilyzer.MeasurementTask createTask(API.TaskType taskType,
                                       java.util.Date startTime,
                                       java.util.Date endTime,
                                       double intervalSec,
                                       long count,
                                       long priority,
                                       int contextIntervalSec,
                                       java.util.Map<java.lang.String,java.lang.String> params)
                                         throws com.mobilyzer.exceptions.MeasurementError

Create a new MeasurementTask based on those parameters. Then submit it to scheduler by addTask or put into task list of parallel or sequential task

Parameters:

taskType - Type of measurement (ping, dns, traceroute, etc.) for this measurement task.

startTime - Earliest time that measurements can be taken using this Task descriptor. The current time will be used in place of a null startTime parameter. Measurements with a startTime more than 24 hours from now will NOT be run.

endTime - Latest time that measurements can be taken using this Task descriptor. Tasks with an endTime before startTime will be canceled. Corresponding to the 24-hour rule in startTime, tasks with endTime later than 24 hours from now will be assigned a new endTime that ends 24 hours from now.

intervalSec - Minimum number of seconds to elapse between consecutive measurements taken with this description.

count - Maximum number of times that a measurement should be taken with this description. A count of 0 means to continue the measurement indefinitely (until end_time).

priority - Two level of priority: USER_PRIORITY for user task and INVALID_PRIORITY for server task

contextIntervalSec - interval between the context collection (in sec)

params - Measurement parameters.

Returns:

Measurement task filled with those parameters

Throws:

com.mobilyzer.exceptions.MeasurementError - taskType is not valid

composeTasks

public com.mobilyzer.MeasurementTask composeTasks(API.TaskType manner,
                                         java.util.Date startTime,
                                         java.util.Date endTime,
                                         double intervalSec,
                                         long count,
                                         long priority,
                                         int contextIntervalSec,
                                         java.util.Map<java.lang.String,java.lang.String> params,
                                         java.util.ArrayList<com.mobilyzer.MeasurementTask> taskList)
                                           throws com.mobilyzer.exceptions.MeasurementError

Create a parallel or sequential task based on the manner. An ArrayList of MeasurementTask must be provided as the real tasks to be executed

Parameters:

manner - Determine whether tasks in task list will be executed parallelly or sequentially (back-to-back)

startTime - Earliest time that measurements can be taken using this Task descriptor. The current time will be used in place of a null startTime parameter. Measurements with a startTime more than 24 hours from now will NOT be run.

endTime - Latest time that measurements can be taken using this Task descriptor. Tasks with an endTime before startTime will be canceled. Corresponding to the 24-hour rule in startTime, tasks with endTime later than 24 hours from now will be assigned a new endTime that ends 24 hours from now.

intervalSec - Minimum number of seconds to elapse between consecutive measurements taken with this description.

count - Maximum number of times that a measurement should be taken with this description. A count of 0 means to continue the measurement indefinitely (until end_time).

priority - Two level of priority: USER_PRIORITY for user task and INVALID_PRIORITY for server task

contextIntervalSec - interval between the context collection (in sec)

params - Measurement parameters.

taskList - tasks to be executed

Returns:

The parallel or sequential task filled with those parameters

Throws:

com.mobilyzer.exceptions.MeasurementError - manner is not valid

submitTask

public void submitTask(com.mobilyzer.MeasurementTask task)
                throws com.mobilyzer.exceptions.MeasurementError

Submit task to the scheduler. Works in async way. The result will be returned in a intent whose action is USER_RESULT_ACTION + clientKey or SERVER_RESULT_ACTION

Parameters:

task - the task to be exectued, created by createTask(..) or composeTask(..)

Throws:

com.mobilyzer.exceptions.MeasurementError

cancelTask

public void cancelTask(java.lang.String taskId)
                throws com.mobilyzer.exceptions.MeasurementError

Cancel the task submitted to the scheduler

Parameters:

localId - task to be cancelled. Got by MeasurementTask.getTaskId()

Throws:

java.security.InvalidParameterException

com.mobilyzer.exceptions.MeasurementError

setAuthenticateAccount

public void setAuthenticateAccount(java.lang.String account)
                            throws com.mobilyzer.exceptions.MeasurementError

Set authenticate account for uploading results. Anonymous by default

Parameters:

account -

Throws:

com.mobilyzer.exceptions.MeasurementError

getAuthenticateAccount

public void getAuthenticateAccount()
                            throws com.mobilyzer.exceptions.MeasurementError

Get current authenticate account used by scheduler

Throws:

com.mobilyzer.exceptions.MeasurementError

setBatteryThreshold

public void setBatteryThreshold(int threshold)
                         throws com.mobilyzer.exceptions.MeasurementError

Set battery threshold of the scheduler. Only a threshold larger than the current one will be accepted.

Parameters:

threshold - new battery threshold, must stay between 0 and 100

Throws:

com.mobilyzer.exceptions.MeasurementError

getBatteryThreshold

public void getBatteryThreshold()
                         throws com.mobilyzer.exceptions.MeasurementError

Get current battery threshold of the scheduler. Async call. Receive api.batteryThresholdAction to get the result

Throws:

com.mobilyzer.exceptions.MeasurementError

setCheckinInterval

public void setCheckinInterval(long interval)
                        throws com.mobilyzer.exceptions.MeasurementError

Set checkin interval of the scheduler. Only an interval larger than the current one will be accepted.

Parameters:

interval - new checkin interval, should be greater than min interval

Throws:

com.mobilyzer.exceptions.MeasurementError

getCheckinInterval

public void getCheckinInterval()
                        throws com.mobilyzer.exceptions.MeasurementError

Get current checkin interval of the scheduler. Async call. Receive api.checkinIntervalAction to get the result

Throws:

com.mobilyzer.exceptions.MeasurementError

getTaskStatus

public void getTaskStatus(java.lang.String taskId)
                   throws com.mobilyzer.exceptions.MeasurementError

Get current status of that task. Async call. Receive api.taskStatusAction to get the result

Parameters:

taskId - the id of the target task

Throws:

com.mobilyzer.exceptions.MeasurementError

setDataUsage

public void setDataUsage(com.mobilyzer.MeasurementScheduler.DataUsageProfile profile)
                  throws com.mobilyzer.exceptions.MeasurementError

Set data usage profile of the scheduler. Only an profile more conventional than the current one will be accepted.

Parameters:

profile - new data usage profile

Throws:

com.mobilyzer.exceptions.MeasurementError

getDataUsage

public void getDataUsage()
                  throws com.mobilyzer.exceptions.MeasurementError

Get current data usage of the scheduler. Async call. Receive api.dataUsageAction to get the result

Throws:

com.mobilyzer.exceptions.MeasurementError

getMeasurementNames

public static java.util.Set<java.lang.String> getMeasurementNames()

Gets the currently available measurement descriptions

getTypeForMeasurementName

public static java.lang.String getTypeForMeasurementName(java.lang.String name)

Get the type of a measurement based on its name. Type is for JSON interface only where as measurement name is a readable string for the UI