Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

For additional information on the IDK, including tutorials, blogs, code samples and more,see the AquaLogic User Interaction Developer Center on BEA dev2dev.

Copyright ©2007 BEA Systems, Inc. All Rights Reserved.