com.plumtree.remote.prc.collaboration.tasklist
Interface ITaskListManager

public interface ITaskListManager

Interface that manages task list creation, copying and removal, and also contains query methods for task lists and tasks.

See Task List Examples.

Method Summary

void	copyTaskLists(IProject sourceProject, IProject targetProject, ITaskList[] sourceTaskLists) Copies an array of task lists from a given source project to a target project.
ITaskFilter	createTaskFilter() Returns a task filter that shows all tasks.
ITaskList	createTaskList(IProject project, java.lang.String name, java.lang.String description) Creates a new task list.
ITaskListFilter	createTaskListFilter() Returns a task list filter that shows all task lists.
int[]	getSubscribedUserIDs(ITaskList taskList) Returns the IDs of the users who are subscribed to the given task list.
ITask	getTask(int taskID) Returns an ITask with the specified ID.
ITaskList	getTaskList(int taskListID) Returns an ITaskList with the specified ID.
ITaskList[]	queryTaskLists(IProject project, ITaskListFilter taskListFilter) Returns ITaskList array in the given project based on the ITaskListFilter.
ITask[]	queryTasks(IProject project, ITaskFilter taskFilter) Returns an ITask array in the given project based on the ITaskFilter.
ITask[]	queryTasks(ITaskList tasklist, ITaskFilter taskFilter) Returns an ITask array in the given task list based on the ITaskFilter.
void	removeTaskList(ITaskList taskList) Removes a task list.
void	subscribeUsers(ITaskList taskList, int[] userIDs) Subscribes users of the given IDs to the given task list.
void	unsubscribeUsers(ITaskList taskList, int[] userIDs) Unsubscribes users with the given ID from a task list.

Method Detail

copyTaskLists

public void copyTaskLists(IProject sourceProject,
                          IProject targetProject,
                          ITaskList[] sourceTaskLists)
                   throws MultipleObjectException,
                          CollaborationException,
                          java.rmi.RemoteException

Copies an array of task lists from a given source project to a target project. If any name collisions occur, the name of the copied object will be modified to make it unique. All copied task lists will be persistent objects.

This method will do a best-attempt to copy the specified task lists. If an error occurs while copying one of the task lists, the copying will continue with appropriate exceptions thrown after the copy process finishes.

The status and risk field of each task in the source task list will be copied, but the assigned to field of each task will not be copied to avoid security discrepancy between the source project and target project.

Both the source project and the target project must be persisted prior to this copy operation.

 //The following sample code shows how to copy task lists from a source project to a target project.
 
 //create the source project, and then persist it.
 IProject sourceProject = projectManager.createProject("Source Project Name", "Source Project Description");
 sourceProject.store();
 //create the target project, and then persist it.
 IProject targetProject = projectManager.createProject("Target Project Name", "Target Project Description");
 targetProject.store();
 
 //create a task list in the soucre project, and then persist it.
 ITaskList tasklist = tasklistManager.createTaskList(sourceProject, "Source Task List Name", "Source Task List Description");
 tasklist.store();
 
 //create a task in the source task list, and then persist it.
 ITask task = tasklist.createTask("Task name", "Task description", new Date(2004, 9, 1), new Date(2004, 9, 8));
 task.store();
 
 //copy the task lists from source project to target project
 //the copied task lists with containing tasks are already persisted by this method
 tasklistManager.copyTaskLists(sourceProject, targetProject, new ITaskList { tasklist } );
 

Parameters:

sourceProject - the project that contains the specified source task lists; cannot be null

targetProject - the target project; cannot be null

sourceTaskLists - an ITaskList array to copy. Each of the task lists must be from the source project and the user must have permission to copy each task list. Cannot be null.

Throws:

CollaborationException - if the method call resulted in an error, or the user does not have Read access to the given projects

java.lang.IllegalArgumentException - if the ID of the sourceProject is not > 0, or the ID of the targetProject is not > 0, or the ID of any of the task lists is not > 0

MultipleObjectException - if errors occurred while copying. Each source exception can be retrieved from this exception. The exception should never happen unless source project content is being accessed concurrently with this copy operation.

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

createTaskFilter

public ITaskFilter createTaskFilter()

Returns a task filter that shows all tasks. The task filter is created with the following defaults: TaskCompletionFilterType is set to ALL, TaskAssignedToFilterType is set to ALL, TaskQueryOrder is set to an array with a single element with the attribute of TaskAttribute.NAME, ascending.

Returns:

a task filter object

createTaskList

public ITaskList createTaskList(IProject project,
                                java.lang.String name,
                                java.lang.String description)

Creates a new task list.

Parameters:

project - the project that the newly-created task list belongs to; cannot be null

name - the task list name; cannot be null

description - the task list description; cannot be null

Returns:

an ITaskList representing the new task list

createTaskListFilter

public ITaskListFilter createTaskListFilter()

Returns a task list filter that shows all task lists. The task list filter is created with the following defaults: TaskListCompletionFilterType is set to ALL, TaskListQueryOrder is set to an array with a single element with the attribute of TaskListAttribute.NAME, ascending.

Returns:

a task list filter

getSubscribedUserIDs

public int[] getSubscribedUserIDs(ITaskList taskList)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Returns the IDs of the users who are subscribed to the given task list.

Parameters:

taskList - the task list; cannot be null

Returns:

the IDs of the users who are subscribed to the task list

Throws:

java.lang.IllegalStateException - if the task list has not yet been stored or has already been removed

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

getTask

public ITask getTask(int taskID)
              throws CollaborationException,
                     java.rmi.RemoteException

Returns an ITask with the specified ID.

Parameters:

taskID - the task ID; must be positive. The ID of an object can be obtained using the getID method in the object class.

Returns:

the task or null if it does not exist or the user does not have permission to see the object

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalArgumentException - if the task ID is not > 0

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

getTaskList

public ITaskList getTaskList(int taskListID)
                      throws CollaborationException,
                             java.rmi.RemoteException

Returns an ITaskList with the specified ID.

Parameters:

taskListID - the task list ID; must be positive. The ID of an object can be obtained using the getID method in the object class.

Returns:

the ITaskList object or null if it does not exist or the user does not have permission to see the object

Throws:

java.lang.IllegalArgumentException - if the taskList ID is not > 0

CollaborationException - if the method call resulted in an error.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

queryTaskLists

public ITaskList[] queryTaskLists(IProject project,
                                  ITaskListFilter taskListFilter)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Returns ITaskList array in the given project based on the ITaskListFilter.

 //The following sample code shows how to query for task lists in a project.
 
 ITaskListFilter taskListFilter = tasklistManager.createTaskListFilter();
 
 //set the query to search for all task list
 // different options can be set to search on task lists that contain only PENDING tasks,
 // completed tasks, or overdue tasks.  See documentation in TaskListCompletionFilterType
 taskListFilter.setCompletionType(TaskListCompletionFilterType.ALL);
 
 //limit the return results to be 10; setting this to 0 will return all results
 taskListFilter.setMaximumResults(10);
 
 //disable security checking on the returned objects against the user who performs this query,
 //so that all objects will be returned
 taskListFilter.setRestoreSecurity(false);
 
 //user TaskListQueryOrder to sort the query result; below TaskListQueryOrder shows sorting the returned task lists by NAME in ascending order
 TaskListQueryOrder taskListQueryOrder = new TaskListQueryOrder(TaskListAttribute.NAME, true);
 taskListFilter.setQueryOrders(new TaskListQueryOrder[] { taskListQueryOrder } );
 
 //an array of ITaskList objects are returned from queryTaskLists(); if no result is retrieved, a zero-length array will be returned
 ITaskList[] retrievedTaskLists = tasklistManager.queryTaskLists(project, taskListFilter);
 

Parameters:

project - the project to query task lists from; cannot be null

taskListFilter - the task list filter to construct the query; cannot be null

Returns:

an ITaskList array of objects in the given project

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalStateException - if the project has not yet been stored or has already been removed

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

queryTasks

public ITask[] queryTasks(IProject project,
                          ITaskFilter taskFilter)
                   throws CollaborationException,
                          java.rmi.RemoteException

Returns an ITask array in the given project based on the ITaskFilter.

 //The following sample code shows how to query for tasks in a project.
 
 ITaskFilter taskFilter = tasklistManager.createTaskFilter();
 
 //search on all tasks; other options include searching for COMPLETED tasks, OVERDUE tasks, or PENDING tasks
 taskFilter.setCompletionType(TaskCompletionFilterType.ALL);
 
 //limit the return results to be 10; setting this to 0 will return all results
 taskFilter.setMaximumResults(10);
 
 //disable security checking on the returned objects against the user who performs this query,
 //so that all objects will be returned
 taskFilter.setRestoreSecurity(false);
 
 //user TaskQueryOrder to sort the query result; below TaskQueryOrder shows sorting the returned task lists by NAME in ascending order
 TaskQueryOrder taskQueryOrder = new TaskQueryOrder(TaskAttribute.NAME, true);
 taskFilter.setQueryOrders(new TaskQueryOrder[] { taskQueryOrder } );
 
 //an array of ITask objects are returned from queryTasks(ITaskList); if no result is retrieved, a zero-length array will be returned
 ITask[] retrievedTasks = tasklistManager.queryTasks(project, taskFilter);
 

Parameters:

project - the project to query tasks from; cannot be null

taskFilter - the task filter to construct the query; cannot be null

Returns:

an ITask array of task objects in the given project

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalStateException - if the project has not yet been stored or has already been removed

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

queryTasks

public ITask[] queryTasks(ITaskList tasklist,
                          ITaskFilter taskFilter)
                   throws CollaborationException,
                          java.rmi.RemoteException

Returns an ITask array in the given task list based on the ITaskFilter.

 //The following sample code shows how to query for tasks in a task list.
 
 ITaskFilter taskFilter = tasklistManager.createTaskFilter();
 
 //search on all tasks; other options include searching for COMPLETED tasks, OVERDUE tasks, or PENDING tasks
 taskFilter.setCompletionType(TaskCompletionFilterType.ALL);
 
 //limit the return results to be 10; setting this to 0 will return all results
 taskFilter.setMaximumResults(10);
 
 //disable security checking on the returned objects against the user who performs this query,
 //so that all objects will be returned
 taskFilter.setRestoreSecurity(false);
 
 //user TaskQueryOrder to sort the query result; below TaskQueryOrder shows sorting the returned task lists by NAME in ascending order
 TaskQueryOrder taskQueryOrder = new TaskQueryOrder(TaskAttribute.NAME, true);
 taskFilter.setQueryOrders(new TaskQueryOrder[] { taskQueryOrder } );
 
 //an array of ITask objects are returned from queryTasks(ITaskList); if no result is retrieved, a zero-length array will be returned
 ITask[] retrievedTasks = tasklistManager.queryTasks(tasklist, taskFilter);
 

Parameters:

tasklist - the task list to query tasks from; cannot be null

taskFilter - the task filter to construct the query; cannot be null

Returns:

an ITask array of task objects in a task list.

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalStateException - if the project has not yet been stored or has already been removed

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

removeTaskList

public void removeTaskList(ITaskList taskList)
                    throws CollaborationException,
                           java.rmi.RemoteException

Removes a task list.

Parameters:

taskList - the task list to remove; cannot be null

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalArgumentException - if the ID of the task is not > 0

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

subscribeUsers

public void subscribeUsers(ITaskList taskList,
                           int[] userIDs)
                    throws MultipleObjectException,
                           CollaborationException,
                           java.rmi.RemoteException

Subscribes users of the given IDs to the given task list.

The calling user must have admin access to the project containing this task list, and the users to be subscribed have to have at least READ access to the task list. The call will make a best attempt to subscribe all supplied, valid users. A MultipleObjectException will be thrown specifying the IDs that failed to be subscribed.

Parameters:

taskList - the task list the users will be subcribed to; cannot be null

userIDs - the IDs of the users to subscribe; cannot be null and all IDs must be positive

Throws:

java.lang.IllegalStateException - if the task list has not yet been stored or has already been removed

java.lang.IllegalArgumentException - if any of the user IDs is not > 0

MultipleObjectException - if any of the users cannot be subscribed

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

unsubscribeUsers

public void unsubscribeUsers(ITaskList taskList,
                             int[] userIDs)
                      throws CollaborationException,
                             java.rmi.RemoteException

Unsubscribes users with the given ID from a task list. Invalid non-negative IDs or IDs that do not describe subscribed users will be ignored.

Parameters:

taskList - the task list ther users will be unsubcribe from; cannot be null

userIDs - the IDs of the users to unsubscribe; cannot be null and all IDs must be positive

Throws:

java.lang.IllegalStateException - if the task list has not yet been stored or has already been removed

java.lang.IllegalArgumentException - if any of the user IDs is not > 0

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call