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

public interface ITaskListManager

ITaskListManager manages task lists 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) Returns a new ITaskList.
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 an array of ITaskList in the given project based on the ITaskListFilter.
ITask[]	queryTasks(IProject project, ITaskFilter taskFilter) Returns an array of ITask in the given project based on the ITaskFilter.
ITask[]	queryTasks(ITaskList tasklist, ITaskFilter taskFilter) Returns an array of ITask 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 of the supplied IDs 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 will need to 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 array of ITaskList to copy. Each of the task lists must be from the sourceProject 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 if the user does not have Read access to the given projects.

java.lang.IllegalArgumentException - if ID of the sourceProject is not > 0, or the ID of the targetProject is not > 0, or 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 is 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)

Returns a new ITaskList.

Parameters:

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

name - task list name; cannot be null.

description - task list description; cannot be null.

Returns:

ITaskList the 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 is 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 the permissions 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 is 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:

ITaskList object or null if it does not exist or the user can't 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 an array of ITaskList 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 array of ITaskList 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 is 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 array of ITask 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 array of ITask objects in a 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 is 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 array of ITask 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 array of ITask objects in a 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 is 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 - task list to remove; cannot be null.

Throws:

CollaborationException - if the method call resulted in an error.

java.lang.IllegalArgumentException - if ID of the task 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.

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; 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 userIDs is not > 0.

MultipleObjectException - if any users cannot be subscribed.

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.

unsubscribeUsers

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

Unsubscribes users of the supplied IDs 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; 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 userIDs 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.