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.project
Interface IProjectManager

public interface IProjectManager

An interface that provides 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 the project content of the source project to the target project.
`IProject` | `copyProjectMetaData(IProject sourceProject, IProject targetProject)` Copies the basic meta-data, 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` | `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 of 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 of 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 the project content of 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 have to be a persisted `IProject`, and also both projects have to have the start date set, otherwise an `CollaborationException` will be thrown. The copied project will be stored permanently. No `store` method will be required to call on the copied object.

  Security is mapped isomorphically from the source project to the target project. Thus 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 has to be persisted prior to call.
    `targetProject` - the target project, cannot be `null` and has to be persisted prior to call.
    `dateShiftType` - a `DateShiftType` specifying how dates in the source project should be shifted to dates in the target project; cannot be `null`. Please see documentation in `DateShiftType` class for more details.
    `timezone` - information for interpreting some of 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 that will 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 have not yet been stored or have already been removed.
    `CollaborationException` - if the method call resulted in an error, or if 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 is 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 meta-data, and all `IRole` objects from the source project to the target project. Prior to the call, the source project has to be a persisted `IProject`, and the target project can be persisted or not. Note that this is different from `copyProjectContent` method where both sourceProject and targetProject have to be stored prior to the call.

  The user needs to be a Project Leader in the target project, and has 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.

  The target project after copied from source project will be returned.

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

  Note that this method does not copy the project content, only the project meta-data. To copy the project content, use `copyProjectContent` method.

  Example code:

       //Sample code for copying projects
       //get the projects - not that 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 is 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` - name of project; cannot be null. Empty strings and duplicate names are valid.
    `description` - description of 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 has a default `ProjectFilterType` of `ProjectFilterType.PROJECTS`, a `ProjectQueryOrder[]` with one element- `ProjectAttribute.NAME`, `ascending`, and the number of projects to return to 0 (unlimited).

  Returns:
    the project filter with default values.

### 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` - when the method call resulted in an error.
    `java.lang.IllegalArgumentException` - if the projectID is not > 0.
    `java.rmi.RemoteException` - if there is 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, the getter methods `getSubscribedUserIDs` in each specific object managers should be used.

  Parameters:
    `project` - the project; cannot be `null`.
  Returns:
    the IDs of the users who are subscribed to a 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 is 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 the 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 is 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 is 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 of 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 other object manager interfaces.

  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 supplied, valid users. 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`; 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 has to 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 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(IProject project,
                                 int[] userIDs)
                          throws CollaborationException,
                                 java.rmi.RemoteException

  Unsubscribes users of 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`; 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 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.