org.eriwen.rtm
[Groovy] Class GroovyRtm

java.lang.Object
  org.eriwen.rtm.GroovyRtm

class GroovyRtm

Provides a Java/Groovy API to access Remember The Milk using their REST API. More details available at http://www.rememberthemilk.com/services/api/

Authors:

Eric Wendelin

Version:

2.1

See Also:

currentUser

public java.lang.String currentUser

lastCallTimeMillis

java.lang.Object lastCallTimeMillis

GroovyRtm

GroovyRtm(java.lang.String configFilePath)

GroovyRtm

GroovyRtm(java.lang.String key, java.lang.String sharedSecret, java.lang.String permissions = 'delete')

authCheckToken

boolean authCheckToken(java.lang.String token)

Checks if the stored auth token is valid by calling the rtm.auth.checkToken REST method from the RTM API

Returns:

True if the stored token is valid, otherwise False

See Also:

authGetFrob

java.lang.String authGetFrob()

Gets an RTM Frob for use with authentication

throws:

GroovyRtmException when the HTTP request failed

Returns:

a new Frob string

See Also:

authGetToken

java.lang.String authGetToken()

Given a frob, gets a new Auth token from RTM. Note that this only needs to occur once per user, per application

Returns:

a new auth token or null if an error occurred

See Also:

contactsAdd

java.lang.String contactsAdd(java.lang.String contact)

Adds a new contact

throws:

GroovyRtmException when the HTTP request failed

Parameters:

contact - should be a username or email address of a Remember The Milk user.

Returns:

the transaction ID or null if an error occurred

See Also:

contactsDelete

java.lang.String contactsDelete(java.lang.String contactId)

Deletes a contact

throws:

GroovyRtmException when the HTTP request failed

Parameters:

contactId - the numeric ID of the contact

Returns:

the transaction ID or null if an error occurred

See Also:

contactsGetList

java.util.List contactsGetList()

Retrieves a List of contacts (id, fullname, and username)

throws:

GroovyRtmException when the HTTP request failed

Returns:

List of LinkedHashMaps representing contacts or null if an error occurred

See Also:

enforceMinDelay

void enforceMinDelay()

Forces successive calls to the RTM API to be spaced by at least the milliseconds specified in API_DELAY_THRESHOLD by putting the execution thread to sleep and synchronizing on the variable used to keep track

execMethod

groovy.util.slurpersupport.GPathResult execMethod(java.util.List params)

Ensures application is authenticated before sending params to be executed

throws:

GroovyRtmException when the HTTP request failed

Parameters:

params - List of URL query parameters

Returns:

GPathResult XML result from the RTM call

execTimelineMethod

groovy.util.slurpersupport.GPathResult execTimelineMethod(java.util.List params)

Adds a timeline to the passed List of URL parameters, creating a timeline if one does not exist

throws:

GroovyRtmException when the HTTP request failed

Parameters:

params - List of URL query parameters

Returns:

GPathResult XML result from the RTM call

execUnauthenticatedMethod

groovy.util.slurpersupport.GPathResult execUnauthenticatedMethod(java.util.List params)

Ensures all criteria is met for making the call to the RTM REST API

throws:

GroovyRtmException when the HTTP request failed

Parameters:

params - List of URL query parameters

Returns:

GPathResult XML result from the RTM call

getAuthToken

java.lang.String getAuthToken(java.lang.String user = null)

getAuthUrl

java.lang.String getAuthUrl()

Initiates RTM authorization by requesting a frob and getting the associated URL

throws:

GroovyRtmException when the HTTP request failed

Returns:

the authorization URL. This is unique for every call to getAuthUrl

getNewAuthToken

java.lang.String getNewAuthToken()

groupsAdd

java.lang.String groupsAdd(java.lang.String groupName)

Adds a new group

throws:

GroovyRtmException when the HTTP request failed

Parameters:

groupName - a valid name for a group of contacts

Returns:

the transaction ID or null if an error occurred

See Also:

groupsAddContact

java.lang.String groupsAddContact(java.lang.String contactId, java.lang.String groupId)

Adds a contact to the specified group

throws:

GroovyRtmException when the HTTP request failed

Parameters:

contactId - the numeric ID of an existing RTM contact

groupId - the numeric ID of an existing RTM group

Returns:

the transaction ID or null if an error occurred

See Also:

groupsDelete

java.lang.String groupsDelete(java.lang.String groupId)

Deletes a group

throws:

GroovyRtmException when the HTTP request failed

Parameters:

groupId - the numeric ID of the group

Returns:

the transaction ID or null if an error occurred

See Also:

groupsGetGroupByName

java.util.Map groupsGetGroupByName(java.lang.String groupName)

Retrieves a Map representing the group with name groupName

throws:

GroovyRtmException when the HTTP request failed

Parameters:

String - group name to search for

Returns:

LinkedHashMap for group if found or null otherwise

groupsGetList

java.util.List groupsGetList()

Retrieves a List of groups (id and name)

throws:

GroovyRtmException when the HTTP request failed

Returns:

List of LinkedHashMaps representing groups

See Also:

groupsRemoveContact

java.lang.String groupsRemoveContact(java.lang.String contactId, java.lang.String groupId)

Deletes a contact from the specified group

throws:

GroovyRtmException when the HTTP request failed

Parameters:

contactId - the numeric ID of an existing RTM contact

groupId - the numeric ID of an existing RTM group

Returns:

the transaction ID or null if an error occurred

See Also:

isAuthenticated

boolean isAuthenticated(java.lang.String user = null)

listsAdd

TaskList listsAdd(java.lang.String listName, java.lang.String filter = null)

Adds a task list

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listName - a valid name for a task list

filter - a String with query words used to create a "Smart" list

Returns:

Map of the new list's attributes or null if an error occurred

See Also:

listsArchive

TaskList listsArchive(java.lang.String listId)

Archives an existing task list

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - an existing list's ID

Returns:

Map of the archived list's attributes or null if an error occurred

See Also:

listsDelete

TaskList listsDelete(java.lang.String listId)

Deletes an existing task list

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - an existing list's ID

Returns:

Map of the deleted list's attributes or null if an error occurred

See Also:

listsGetList

java.util.List listsGetList()

Retrieves a List of task lists

throws:

GroovyRtmException when the HTTP request failed

Returns:

List of LinkedHashMaps containing ID and name or null if an error occurred

See Also:

listsGetListByName

TaskList listsGetListByName(java.lang.String listName)

Retrieves a Map representing the list with name listName

throws:

GroovyRtmException when the HTTP request failed

Returns:

LinkedHashMap for list if found or null otherwise

listsSetDefaultList

boolean listsSetDefaultList(java.lang.String listId = null)

Sets the given list as default (new tasks go there unless specified otherwise), or Inbox if the list isn't provided

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - the numeric ID of the task list to set as default. If null, will default to the user's Inbox

Returns:

Returns true if the specified listId was successfully set as default

See Also:

listsSetName

TaskList listsSetName(java.lang.String listId, java.lang.String newName)

Sets the name of a given list

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - an existing list's ID

newName - the new name of the list

Returns:

Map of the changed list's attributes or null if an error occurred

See Also:

listsUnarchive

TaskList listsUnarchive(java.lang.String listId)

Un-archives an existing, archived task list

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - an existing list's ID

Returns:

Map of the un-archived list's attributes or null if an error occurred

See Also:

locationsGetList

java.util.List locationsGetList()

Retrieves a List of locations (id and name)

throws:

GroovyRtmException when the HTTP request failed

Returns:

List of LinkedHashMaps representing locations

See Also:

locationsGetLocationByName

java.util.Map locationsGetLocationByName(java.lang.String locationName)

Retrieves a location specified by name

throws:

GroovyRtmException when the HTTP request failed

Parameters:

locationName - the name of an existing location

Returns:

Map containing ID and Name of the location or null if an error occurred

removeAuthToken

void removeAuthToken(java.lang.String user = null)

setAuthToken

void setAuthToken(java.lang.String token, java.lang.String user = null)

settingsGetList

java.util.Map settingsGetList()

Retrieves a Map of user settings (timezone, time format, language, etc.)

throws:

GroovyRtmException when the HTTP request failed

Returns:

LinkedHashMap with RTM-specific settings

See Also:

tasksAdd

Task tasksAdd(java.lang.String name, java.lang.String listId = null, java.lang.Object parse = false)

Adds a task to a list, optionally parsing out a due date

throws:

GroovyRtmException when the HTTP request failed

Parameters:

name - a valid name for a task

listId - ID of the list to add the task to. Defaults to the user's default list

parse - enables parsing the task name for a due date if true (default is false)

Returns:

Map of the new task's attributes or null if an error occurred

See Also:

tasksAdd

Task tasksAdd(java.lang.String name, java.lang.String priority, java.lang.String due, java.lang.String estimate, java.lang.String repeat, java.lang.String tags, java.lang.String locationId, java.lang.String url, java.lang.String listId = null)

Adds a task with lots of options to a given or default list.

throws:

GroovyRtmException when the HTTP request failed

Parameters:

name - a valid name for a task

priority - the priority of the task. Can be null

due - a due date for the task. Can be null

estimate - the estimated effort. Can be null

repeat - string representing how often this task should repeat. Can be null

tags - the tags associated with the task. Can be null

locationId - the ID of the location to associate with the task. Can be null

url - a URL to associate with the task. Can be null

listId - ID of the list to add the task to. Defaults to the user's default list

Returns:

Map of the new task's attributes or null if an error occurred

tasksAddTags

Task tasksAddTags(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String tags)

Adds tags to an existing task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

tags - comma separated list of tags to add

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksComplete

Task tasksComplete(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId)

Completes a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksDelete

Task tasksDelete(java.lang.String listId, java.lang.String taskSeriesId, java.lang.String taskId)

Deletes a specified task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

Returns:

Map of the deleted task's attributes or null if an error occurred

See Also:

tasksGetList

java.util.List tasksGetList(java.lang.String listId = null, java.lang.String filter = null, java.lang.String lastSync = null)

Retrieves a List of tasks

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - (optional) if specified, the list from which to get tasks. Defaults to all lists

filter - (optional) if specified, a filter to be applied to tasks.

lastSync - (optional) An ISO 8601 formatted time value. If last_sync is provided, only tasks modified since last_sync will be returned

Returns:

List of RTM tasks

See Also:

tasksMovePriority

Task tasksMovePriority(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, boolean increasePriority)

Adjusts the specified task's priority 1 step up or down

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

increasePriority - will increase priority by 1 if true otherwise decrease

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksMovePriority

Task tasksMovePriority(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String direction)

Adjusts the specified task's priority 1 step up or down

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

direction - "up" or "down"

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksMoveTo

Task tasksMoveTo(java.lang.String fromListId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String toListId)

Moves a given task to another list

throws:

GroovyRtmException when the HTTP request failed

Parameters:

fromListId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

toListId - ID of the list to move the task to

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksNotesAdd

Note tasksNotesAdd(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String noteTitle, java.lang.String noteText)

Adds a new note to a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

noteTitle - title of the note

noteText - body of the note

Returns:

Map of the new note's attributes or null if an error occurred

See Also:

tasksNotesDelete

boolean tasksNotesDelete(java.lang.String noteId)

Adds a new note to a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

noteId - ID of the note

Returns:

Returns true if the note was successfully deleted, otherwise false

See Also:

tasksNotesEdit

Note tasksNotesEdit(java.lang.String noteId, java.lang.String noteTitle, java.lang.String noteText)

Modifies a note

throws:

GroovyRtmException when the HTTP request failed

Parameters:

noteId - ID of the note to be modified

noteTitle - new title of the note

noteText - new body of the note

Returns:

Map of the modified note's attributes or null if an error occurred

See Also:

tasksPostpone

Task tasksPostpone(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId)

Postpones a task 1 day

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksRemoveTags

Task tasksRemoveTags(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String tags)

Removes tags from an existing task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

tags - comma separated list of tags to remove

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetDueDate

Task tasksSetDueDate(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String due = null, boolean hasDueTime = false, boolean parse = false)

Sets the due date of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

due - (optional) Due date for a task, in ISO 8601 format. If parse is specified and has a value of 1, due is parsed as per rtm.time.parse. due is parsed in the context of the user's Remember The Milk timezone.

hasDueTime - (optional) true if this date has a time associated with it. Default is false

parse - (optional) Specifies whether to parse due with rtm.time.parse. Default is false

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetEstimate

Task tasksSetEstimate(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String estimate = null)

Sets the estimate of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

estimate - (optional) The time estimate for a task. Specified in units of days, hours or minutes. If left as null, any existing time estimate will be unset.

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetLocation

Task tasksSetLocation(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String locationId = null)

Sets the location of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

locationId - (optional) The id of a location. If left as null, any existing location will be unset.

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetName

Task tasksSetName(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String name)

Sets the name of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

name - new name for the task

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetPriority

Task tasksSetPriority(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String priority = null)

Sets the priority of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

priority - (optional) "1", "2", "3" or "N". If left as null, priority defaults to "N"

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetRecurrence

Task tasksSetRecurrence(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String repeat = null)

Sets the recurrance of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

repeat - (optional) The recurrence pattern for a task. Valid values of repeat are detailed here. An empty value unsets any existing recurrence pattern.

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetTags

Task tasksSetTags(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String tags = null)

Sets the tags of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

tags - (optional) A comma delimited list of tags. An empty value removes any existing tags.

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksSetUrl

Task tasksSetUrl(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId, java.lang.String url = null)

Sets the URL of a task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

url - (optional) The URL associated with a task. Valid protocols are http, https, ftp and file. If left empty, any existing URL will be unset

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

tasksUncomplete

Task tasksUncomplete(java.lang.String listId, java.lang.String taskseriesId, java.lang.String taskId)

Un-completes a completed task

throws:

GroovyRtmException when the HTTP request failed

Parameters:

listId - ID of the list containing the task to be modified

taskseriesId - ID of the taskseries containing the task to be modified

taskId - ID of the task to be modified

Returns:

Map of the modified task's attributes or null if an error occurred

See Also:

testEcho

boolean testEcho()

Checks the API key and tests connectivity to Remember The Milk

throws:

GroovyRtmException when the HTTP request failed

Returns:

Returns true if the test was successful

See Also:

testLogin

boolean testLogin()

Checks if the application is logged in

throws:

GroovyRtmException when the HTTP request failed

Returns:

Returns true if the application is logged in to RTM

See Also:

timeConvert

java.lang.String timeConvert(java.lang.String toTimezone, java.lang.String fromTimezone = null, java.util.Date time = null)

Returns the specified time in the desired timezone.

throws:

GroovyRtmException when the HTTP request failed

Parameters:

toTimezone - Target timezone. A list of valid timezones can be retrieved with timezonesGetList

fromTimezone - (optional) Originating timezone. Defaults to UTC if left null

time - (optional) Time to convert in ISO 8601 format. Defaults to now

Returns:

String containing the ISO 8601 date

See Also:

timeParse

java.lang.String timeParse(java.lang.String text, java.lang.String timezoneId = null, boolean europeanFormat = false)

Returns the specified time in the desired timezone.

throws:

GroovyRtmException when the HTTP request failed

Parameters:

text

timezoneId - (optional) If specified, text is parsed in the context of timezone. A list of valid timezones can be retrieved with timezonesGetList. Defaults to UTC

europeanFormat - (optional) true indicates an European date format (14/02/2006). false indicates an American date format (02/14/2006). This value is used in case a date is ambiguous. Default is false

Returns:

String containing the ISO 8601 date

See Also:

timelinesCreate

java.lang.String timelinesCreate()

Creates a timeline to allow operations to be undone

throws:

GroovyRtmException when the HTTP request failed

Returns:

String with the timeline ID

See Also:

timezonesGetList

java.util.List timezonesGetList()

Retrieves a List of timezones (id, name, dst, offset, currentOffset)

throws:

GroovyRtmException when the HTTP request failed

Returns:

List of LinkedHashMaps representing timezones

See Also:

timezonesGetTimezoneByName

Timezone timezonesGetTimezoneByName(java.lang.String timezoneName)

Retrieves a timezone specified by name

throws:

GroovyRtmException when the HTTP request failed

Parameters:

timezoneName - the name of a timezone

Returns:

Map containing timezone info for the timezone or null if the timezone could not be found

transactionsUndo

boolean transactionsUndo(java.lang.String transactionId)

Reverts the affects of an action.

throws:

GroovyRtmException when the HTTP request failed

Parameters:

transactionId - the ID of a transaction within a timeline

Returns:

List of LinkedHashMaps representing timezones

See Also:

Groovy Documentation