com.plumtree.remote.prc.collaboration.project
Interface IProjectManager

public interface IProjectManager

Interface that provides Collaboration project management functionality, including project creation, copying, removal, query and project URL creation. See Project Examples.

Method Summary

void	copyProjectContent(IProject sourceProject, IProject targetProject, DateShiftType dateShiftType, java.util.TimeZone timezone, java.lang.String documentHistoryComment) Copies all project content from the source project to the target project.
IProject	copyProjectMetaData(IProject sourceProject, IProject targetProject) Copies the basic metadata and all IRole objects from the source project to the target project.
IProject	createProject(java.lang.String name, java.lang.String description) Returns a new project object.
IProjectFilter	createProjectFilter() Creates a project filter for querying projects.
IProject	getCommunityProject(int communityID) Gets the user's personal project.
IProject	getPersonalProject() Gets the user's personal project.
IProject	getProject(int projectID) Returns a project by its ID.
int[]	getSubscribedUserIDs(IProject project) Returns the IDs of the users who are subscribed to the given project.
IProject[]	queryProjects(IProjectFilter projectFilter) Returns an array of projects with the specified project filter.
void	removeProject(IProject project) Removes a project.
void	subscribeUsers(IProject project, int[] userIDs, boolean notifyForAllCreation) Subscribes users with the given IDs to a project, with an option of whether the users being subscribed will get notified for all new object creations in that project.
void	unsubscribeUsers(IProject project, int[] userIDs) Unsubscribes users with the given IDs from a project.

Method Detail

copyProjectContent

public void copyProjectContent(IProject sourceProject,
                               IProject targetProject,
                               DateShiftType dateShiftType,
                               java.util.TimeZone timezone,
                               java.lang.String documentHistoryComment)
                        throws PermissionDeniedException,
                               MultipleObjectException,
                               CollaborationException,
                               java.rmi.RemoteException

Copies all project content from the source project to the target project. This asynchronous method will do a best-attempt effort to copy all the objects in the source project. If an error occurs while copying one of the objects, the copying will continue with appropriate exceptions thrown after the copy process finishes.

This method may only be invoked on behalf of a user who is a project leader in both the source and the target projects.

The project data that is copied is:

1. All document folders
2. All documents
3. All discussions (but not the discussion messages)
4. All task lists
5. All tasks

Prior to the call, both the source and target project must be a persisted IProject, and both projects must have the start date set, otherwise an CollaborationException will be thrown. The copied project will be stored permanently. No store method is required on the copied object.

Security is mapped isomorphically from the source project to the target project. For example, if the ProjectMember role in the source project has access level i on object O, and object O is copied to object O', then the ProjectMember role in the target project will have access level i on object O'. Similarly with the ProjectGuest role.

Example code:

 //Sample code for copying projects //get the projects
 IProject sourceProject = projectManager.getProject(sourceProjectID);
 IProject targetProject = projectManager.getProject(targetProjectID); 

 //use DateShiftType of NONE for no date conversions DateShiftType
 dateShiftType = DateShiftType.NONE; 
 //use the default timezone- see
 docs for other options TimeZone timezone = TimeZone.getDefault(); try
 {   projectManager.copyProjectContent(sourceProject,
 targetProject, dateShiftType, timezone); } catch (Exception e)
 {   if (e instanceof MultipleObjectException)
   {      //get the source exception from
 each exception      MultipleObjectException multException =
 (MultipleObjectException) e;      int[] ids =
 multException.getIds();      for (int i = 0; i <
 ids.length; i++)      {
         Exception causeException =
 multException.getCauseException(ids[i]);       
 //deal with the cause exception....      }
   }   else   {     
 //deal with other exceptions......    } } 

 
 

Parameters:

sourceProject - the source project; cannot be null and must be persisted prior to call

targetProject - the target project; cannot be null and must be persisted prior to call

dateShiftType - a DateShiftType specifying how dates in the source project should be shifted to in the target project; cannot be null. See documentation in the calendar.DateShiftType class for more details.

timezone - information for interpreting source dates. This should be set to the time zone of the user on whose behalf the copying is being done; cannot be null.

documentHistoryComment - a string to be used as the initial comment in the document history of each of the copied documents

Throws:

PermissionDeniedException - if the user is not a Project Leader in both the source and target project

java.lang.IllegalStateException - if either of the projects has not yet been stored or have already been removed

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

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

copyProjectMetaData

public IProject copyProjectMetaData(IProject sourceProject,
                                    IProject targetProject)
                             throws CollaborationException,
                                    java.rmi.RemoteException

Copies the basic metadata and all IRole objects from the source project to the target project. Prior to the call, the source project must be a persisted IProject, and the target project can be persisted or not. Note: This is different from copyProjectContent method where both the source project and target project must be stored prior to the call.

The user must be a Project Leader in the target project, and must have READ access in the source project.

The method will copy all of the following: project description, all IRole objects, and start date information if the target project's start date is not set and the source project's start date is available.

After the copy process is complete, the target project will be returned.

The copied project will be stored permanently. No store method is required on the copied object. WARNING: The old roles in the target project will be overwritten with the copied roles from the source project.

Note: This method does not copy the project content, only the project metadata. To copy the project content, use copyProjectContent.

Example code:

 //Sample code for copying projects //get
 the projects - the targetProject does not have to be stored IProject
 sourceProject = projectManager.getProject(sourceProjectID); IProject
 targetProject = projectManager.getProject(targetProjectID);
 projectManager.copyProjectMetaData(sourceProject, targetProject); 

 
 

Parameters:

sourceProject - the source project to copy from; cannot be null

targetProject - the target project to copy to; cannot be null

Returns:

the target project after copied from source project

Throws:

java.lang.IllegalStateException - if the source project has not yet been stored or if either of the projects have already been removed

CollaborationException - if the user is not a Project Leader in the target project or 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

createProject

public IProject createProject(java.lang.String name,
                              java.lang.String description)

Returns a new project object. The newly created project will not be persisted until store method is called on the project.

Parameters:

name - the name of the project; cannot be null. Empty strings and duplicate names are valid.

description - the description of the project; cannot be null. Empty strings are valid.

Returns:

a new project object

createProjectFilter

public IProjectFilter createProjectFilter()

Creates a project filter for querying projects. The project filter uses the follwing defaults: ProjectFilterType of PROJECTS, a ProjectQueryOrder[] with one element: ProjectAttribute.NAME, ascending order, and the number of projects to return to 0 (unlimited).

Returns:

the project filter with default values

getCommunityProject

public IProject getCommunityProject(int communityID)
                             throws PermissionDeniedException,
                                    CollaborationException,
                                    java.rmi.RemoteException

Gets the user's personal project.

Parameters:

communityID - the community ID; must be positive.

Returns:

thedefault project for the specified communityID, or null if the community has no project.

Throws:

java.lang.IllegalArgumentException - if the projectID is not > 0

PermissionDeniedException - if the user does not have rights to retrieve the community project*

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

getPersonalProject

public IProject getPersonalProject()
                            throws PermissionDeniedException,
                                   CollaborationException,
                                   java.rmi.RemoteException

Gets the user's personal project.

Returns:

the user's personal project. If the personal project does not exist and the user has rights to create a personal project, the personal project will be created and returned

Throws:

PermissionDeniedException - if the user does not have rights to create a personal project*

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

getProject

public IProject getProject(int projectID)
                    throws CollaborationException,
                           java.rmi.RemoteException

Returns a project by its ID.

Parameters:

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

Returns:

the project or null if the project does not exist or the user does not have permission to see the project

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalArgumentException - if the projectID is not > 0

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

getSubscribedUserIDs

public int[] getSubscribedUserIDs(IProject project)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Returns the IDs of the users who are subscribed to the given project. To retrieve the users who are subscribed to a specific object, use the getter methods getSubscribedUserIDs in each specific object manager.

Parameters:

project - the project; cannot be null

Returns:

the IDs of the users who are subscribed to the project

Throws:

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

CollaborationException - if the method resulted in an error

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

queryProjects

public IProject[] queryProjects(IProjectFilter projectFilter)
                         throws CollaborationException,
                                java.rmi.RemoteException

Returns an array of projects with the specified project filter. Different filter options can be set using projectFilter.

 //The following sample code shows how to query for projects
 that contains "devkit" in its name. IProjectFilter projectFilter =
 projectManager.createProjectFilter();
 projectFilter.setNameSearchText("devkit"); IProject[] returnedProjects =
 projectManager.queryProjects(projectFilter);
 
 

Parameters:

projectFilter - the project filter, used for querying projects by names; cannot be null and must contain a filter type and query order

Returns:

an array of zero or more IProject objects

Throws:

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

removeProject

public void removeProject(IProject project)
                   throws CollaborationException,
                          java.rmi.RemoteException

Removes a project.

Parameters:

project - the project to remove; cannot be null

Throws:

java.lang.IllegalStateException - if the project 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

subscribeUsers

public void subscribeUsers(IProject project,
                           int[] userIDs,
                           boolean notifyForAllCreation)
                    throws CollaborationException,
                           MultipleObjectException,
                           java.rmi.RemoteException

Subscribes users with the given IDs to a project, with an option of whether the users being subscribed will get notified for all new object creations in that project.

To subscribe users to a specific object in a project, use the subscribeUsers method in the object manager interface.

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

Parameters:

project - the project to subscribe users to; cannot be null

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

notifyForAllCreation - true if the given users to be subscribed will get notified upon all new object creations in the project; false if the users will only get notified once upon being subscribed. Notification server must be enabled for this to take effect.

Throws:

java.lang.IllegalStateException - if the project 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(IProject project,
                             int[] userIDs)
                      throws CollaborationException,
                             java.rmi.RemoteException

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

Parameters:

project - the project to unsubscribe users from; cannot be null and all IDs must be positive

userIDs - the IDs of the users to unsubscribe from the project; cannot be null

Throws:

java.lang.IllegalStateException - if the project 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 was a communication problem during the execution of the remote method call